package com.kun.companion.core.queue.enums;

/**
 * 事件优先级枚举
 *
 * <p>定义任务调度系统中的事件处理优先级，数值越小优先级越高
 *
 * <p>典型应用场景：
 * <ul>
 *   <li>CRITICAL - 系统关键操作（如支付回调、紧急状态更新）</li>
 *   <li>HIGH     - 重要用户操作（如订单提交、即时消息）</li>
 *   <li>NORMAL   - 常规业务流程（如数据同步、日志处理）</li>
 *   <li>LOW      - 后台任务（如报表生成、数据归档）</li>
 * </ul>
 *
 * @author gzc
 * @since 2025/2/3
 */
public enum EventPriorityEnum {
    /**
     * 最高优先级（数值0）<br>
     * 适用于必须立即处理的关键任务，会抢占线程池资源
     */
    CRITICAL(0),

    /**
     * 高优先级（数值1）<br>
     * 适用于重要业务流程，在系统资源充足时优先于普通任务
     */
    HIGH(1),

    /**
     * 普通优先级（数值2）<br>
     * 默认任务级别，按先进先出顺序处理
     */
    NORMAL(2),

    /**
     * 低优先级（数值3）<br>
     * 仅在系统空闲时处理，可能被高优先级任务抢占
     */
    LOW(3);

    private final int priorityValue;

    /**
     * 枚举构造函数
     *
     * @param value 优先级数值（必须唯一）
     */
    EventPriorityEnum(int value) {
        this.priorityValue = value;
    }

    /**
     * 获取优先级数值
     *
     * @return 表示优先级的整数值（数值越小优先级越高）
     */
    public int getValue() {
        return priorityValue;
    }

    /**
     * 通过数值获取对应优先级枚举
     *
     * @param value 优先级数值
     * @return 对应的EventPriority枚举实例
     * @throws IllegalArgumentException 当传入无效数值时抛出
     */
    public static EventPriorityEnum fromValue(int value) {
        for (EventPriorityEnum priority : EventPriorityEnum.values()) {
            if (priority.priorityValue == value) {
                return priority;
            }
        }
        throw new IllegalArgumentException("无效的优先级数值: " + value);
    }

    /**
     * 验证数值有效性
     *
     * @param value 待验证的数值
     * @return 是否为有效优先级数值
     */
    public static boolean isValid(int value) {
        for (EventPriorityEnum priority : EventPriorityEnum.values()) {
            if (priority.priorityValue == value) {
                return true;
            }
        }
        return false;
    }
}